Docs: Adding an index and clarifying suggested usage #116
Conversation
This PR does a couple of things: 1. Rewords the intro paragraph a bit to be slightly less technical 2. Adds a table of contents 3. Adjusts the installation instructions to promote the usage of the .phar approach over the dev dependency approach 4. Tweaks the `Usage` section to show a couple ways to execute Strauss 5. Removes the `dump-autoload` recommendation in favor of just recommending it always. Let me know if you'd like me to break these doc changes out into separate PRs so you can accept or deny them on their own!
|
|
||
| A fork of [Mozart](https://github.com/coenjacobs/mozart/). For [Composer](https://getcomposer.org/) for PHP. | ||
| A fork of [Mozart](https://github.com/coenjacobs/mozart/) for [Composer](https://getcomposer.org/) for PHP. |
There was a problem hiding this comment.
I was using the punctuation as emphasis. I think both are valid and neither is better.
|
|
||
| The primary use case is WordPress plugins, where different plugins active in a single WordPress install could each include different versions of the same library. The version of the class loaded would be whichever plugin registered the autoloader first, and all subsequent instantiations of the class will use that version, with potentially unpredictable behaviour and missing functionality. | ||
| Have you ever activated a WordPress plugin that has a conflict with another because the plugins use two different versions of the same PHP library? **Strauss is the solution to that problem** - it ensures that _your_ plugin's PHP dependencies are isolated and loaded from your plugin rather than loading from whichever plugin's autoloader registers & runs first. |
There was a problem hiding this comment.
Not the tone I would go for exactly. But my paragraph wasn't beautiful either.
|
|
||
| Require as normal with Composer: | ||
| ### As a `.phar` file (recommended) |
There was a problem hiding this comment.
I think Phive, phar.io, is the ideal way, but it's not how I use it myself so I'm hesitant to write documentation for something I don't do myself.
Also is using bin as the directory for downloaded tools convention? It is for the tools being distributed. Easily manageable with .gitignore as you're recommending.
Line 14 in 3035f84
|
|
||
| ```json | ||
| "scripts": { | ||
| "prefix-namespaces": [ | ||
| "strauss" | ||
| "sh -c 'test -f ./bin/strauss.phar || curl -o bin/strauss.phar -L -C - https://github.com/BrianHenryIE/strauss/releases/latest/download/strauss.phar'", |
There was a problem hiding this comment.
Why is sh -c needed? I think that should work anyway. Maybe for GitHub Actions?
There was a problem hiding this comment.
Without sh -c, the initial run when the phar file does not exist downloads and errors out the command. Wrapping in the sh -c allows it to do the download in isolation and then continue on with the composer command without error.
Perhaps there’s a cleaner way, but that is what I use!
| or | ||
| This provides `composer strauss`, which does the following: | ||
|
|
||
| 1. The `sh -c` command tests if `bin/strauss.phar` exists, and if not, downloads it from [releases](https://github.com/BrianHenryIE/strauss/releases). |
There was a problem hiding this comment.
test -f tests does it exist. sh -c starts a new shell for the quoted commands.
There was a problem hiding this comment.
Yeah, the intent of the sh -c callout was to reference the line itself, not just the sh -c portion. Your point is good, though :)
|
|
||
| ### As a dev dependency via composer (not recommended) | ||
|
|
||
| If you prefer to include Strauss as a dev dependency, you can still do so. You mileage may vary when you include it this way. |
There was a problem hiding this comment.
A bit vague. ~"This will not work if your plugin targets a version lower than Strauss's minimum, 7.4, or if Strauss happens to have dependency requirements whose versions constrains are incompatible with other packages you are installing"
This PR does a couple of things:
Usagesection to show a couple ways to execute Straussdump-autoloadrecommendation in favor of just recommending it always.Let me know if you'd like me to break these doc changes out into separate PRs so you can accept or deny them on their own! I definitely made some assumptions based on StellarWP's heavy usage of the tool 🕺